home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / PROGEDIT / 2285.ZIP / MANUALS.EXE / PRINTDOC.DOC < prev    next >
Text File  |  1990-08-19  |  11KB  |  207 lines
  1.                            PRINTDOC UTILITY
  2.                            ****************
  3.  
  4.  
  5.          This program was written to solve a specific problem, namely the
  6. creation and maintenance of manuals. Essentially the program will format a
  7. text file and break it up into numbered pages, with a user specified number
  8. of lines per page. The concept is very simple, but when you try to write
  9. a program to a acheive this in a logical and intelligent manner you realise
  10. that the procedure needs to be fairly sophisticated in order to work in an
  11. acceptable manner.
  12.          Let us suppose for a moment that you have created a document using
  13. a text editor which has created a clean ASCII file (Non-Document Mode) which
  14. consists of 10-15 pages and you have layed out each page in a tidy format
  15. with page breaks occuring in sensible places. At the end of this document you
  16. have created a small index which lists all the major chapter heading along
  17. with the relevant page numbers. Then, sometime later, you need to update the
  18. manual and perhaps add some new paragraphs/pages somewhere near the start of
  19. the document. Immediately you realise that there going to be some problems.
  20. For instance lets take a small example as shown below :-
  21.  
  22. Fig 1.   This example shows how your original document might look before
  23.          you have made any modifications.
  24.  
  25.    /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 
  26.    │                                             │
  27.    │ Delete a Line                               │
  28.    │ -------------                               │  Bottom of Page 5
  29.    │   To delete a line you should press ALT + D │
  30.    │                                             │
  31.    │                      5                      │
  32.    └─────────────────────────────────────────────┘
  33.    ┌─────────────────────────────────────────────┐
  34.    │                                             │
  35.    │ Insert a Line                               │  Top of Page 6
  36.    │ -------------                               │
  37.    │   To insert a line you should press ALT + I │
  38.    \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/  
  39.  
  40. Fig 2.   Then lets suppose that you add some more text to the start of page 5
  41.          and see what happens with a lot of word processors
  42.  
  43.    /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 
  44.    │                                             │
  45.    │ will split a line at the cursor position.   │<-- The new line(s) added
  46.    │                                             │    here
  47.    │ Delete a Line                               │
  48.    │                      5                      │<-- has caused the following
  49.    └─────────────────────────────────────────────┘    paragraphs to be moved
  50.    ┌─────────────────────────────────────────────┐    down with the result that
  51.    │ -------------                               │    this section has now
  52.    │   To delete a line you should press ALT + D │    become separated from its
  53.    │                                             │    title.
  54.    │ Insert a Line                               │
  55.    │ -------------                               │
  56.    │   To insert a line you should press ALT + I │
  57.    \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/  
  58.  
  59.    Apart from the above difficulty you would also need to check all the
  60. page references in your Index/Contents page. 
  61.  
  62.    The PRINTDOC Utility program goes a long way to solving all of these 
  63. problems. In the above examples you noticed how text can easily be split
  64. across two pages in a rather ugly manner. To correct this problem you need
  65. to make some changes to your original document. In effect you need to add some
  66. page formatting rules. The following example demonstrates the use of two
  67. simple commands that you can include in your text which when processed by
  68. PRINTDOC will ensure that this type of error does not occur.
  69.  
  70.                         /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 
  71.                        │                                             │
  72.  Do not allow a   ---->│/NOBREAK/                                    │
  73.  page break to occur   │ Delete a Line                               │
  74.  from now onwards.     │ -------------                               │
  75.                        │   To delete a line you should press ALT + D │
  76.  Re-enable page   ---->│/BREAK/                                      │
  77.  breaks.               │                                             │
  78.                         \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
  79.  
  80.  
  81.          When you printout your document using the PRINTDOC Utility program
  82. it will realise that you have marked a block of text and only start printing
  83. it on the current page if all of it is going to fit on the current page,
  84. otherwise a page break is inserted and the entire block of text is placed
  85. on the following page.
  86.  
  87.  
  88.          Another consequence of you inserting text at the start of a  
  89. document is that your Index/Contents Page references need altering. The
  90. PRINTDOC Utility has the ability to automatically create a Contents Page for 
  91. you. To place an item in the index you should simple enclose it in the brackets
  92. as shown below :-
  93.  
  94.    ┌─────────────────────────────────────────────┐
  95.    │                                             │
  96.    │ {[Insert a Line}]                           │
  97.    │ -------------                               │
  98.    │   To insert a line you should press ALT + I │
  99.    \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/  
  100.  
  101.    Note that the order of the {[ and }] brackets remains the same. i.e. they
  102. are not mirror images. This was done because it seemed easier to follow the
  103. same key sequence (Press Shift First) for both sets of brackets.
  104.  
  105.          When the PRINTDOC programs reads a line containing an index entry 
  106. is calculates what page that line will be on when the document is printed
  107. and stores it in memory. Then when all of the document has been printed all
  108. of these entries are sorted into alphabetical sequence and printed out.
  109. Any duplicate index entries will result in a index entry being given two
  110. page numbers in the index. Multiple page references for a single index entry
  111. are ignored.
  112.  
  113.          Sometimes you may wish to include an entry in the index which does
  114. not occur in the text. Take for example the following title taken from a
  115. ducument:-
  116.  
  117.    ┌─────────────────────────────────────────────┐
  118.    │                                             │
  119.    │ {[ALT + D (Delete Line)}]                   │
  120.    │ ---------------------                       │
  121.    │                                             │
  122.    \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/  
  123.  
  124.          As it is shown above you will only get one reference to this
  125. subject in the Contents Page which might look like.
  126.  
  127.    ┌─────────────────────────────────────────────┐
  128.    │             C O N T E N T S                 │
  129.    │                                             │
  130.    │ ALT + D (Delete Line)   5                   │
  131.    │                                             │
  132.    \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/  
  133.  
  134.          It would however be desirable to have another reference to this
  135. subject under "Delete Line - ALT 5" in case the person looking in the index
  136. did not know the key combination in question.
  137.          To add a reference to the index which does not occur in the text
  138. itself you must use another command as shown below :-
  139.  
  140.                           ┌─────────────────────────────────────────────┐
  141.                           │                                             │
  142.                           │ ALT + D (Delete Line)                       │
  143.   The COMMENT command --->│/COMMENT/{[Delete Line - ALT F5}]            │
  144.   will be ignored by      │ ---------------------                       │
  145.   PRINTDOC but can be     │                                             │
  146.   used to add other       \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/  
  147.   index entries.
  148.  
  149.            You should notice that any index items found on a comment line 
  150. will be attributed to the same line and page as the last Non-Comment Line.
  151.  
  152.            Other useful command sequences which you can embed in your text
  153. files aree /DEFINE/ and /ENDDEFINE/. To best explain their use it is 
  154. necessary to show an example :-
  155.  
  156.    ┌─────────────────────────────────────────┐
  157.    │/DEFINE/                                 │
  158.    │"U1" EQU "HELLO"                         │
  159.    │"U0" EQU "WORLD"                         │
  160.    │/ENDDEFINE/                              │
  161.    │                                         │
  162.    │                                         │
  163.    │                                         │
  164.     \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/  
  165.  
  166.      The above example shows how you can define some variables. If at any
  167. point after these definitions have taken place the PRINTDOC finds one of
  168. these variable names in your text it will automatically be replaced by the
  169. appropriate string. 
  170.  
  171.               i.e   U1 would be replaced with HELLO
  172.  
  173.     This feature is especially useful for defining printer codes. You could
  174. use U1 to turn on underlined print and U0 for turning off underlined print.
  175. You may like to set up BOLDON and BOLDOFF similarly for BOLD printing.
  176.  
  177.     One printer effect has been built into the program and will give you a
  178. shaded background effect. To use this printer effect you should surround 
  179. the string as follows :-
  180.  
  181.           /HI/Test String/LO/
  182.  
  183.     This effect has been hard coded and as yet cannot be reconfigured if it
  184. does not work with your printer. One note to remember is that this effect
  185. cannot be used over any IBM line characters (ASCII 176-223). This limitation
  186. may be removed later on.
  187.  
  188.      The ASCII character used to overtype the line and create the shading
  189. effect is 176 ░ but you can change this with a command in your text file. To
  190. change the character you should use the following command in the syntax shown
  191. below :-
  192.            /SHADING/▓
  193.  
  194.       There is one important note to remember when changing the shading 
  195. pattern. If you change the shading character in a block of text which has
  196. been defined as a /NOBREAK/ area then all the lines defined will be printed
  197. using the last /SHADING/ definition found within that block. Outside a 
  198. /NOBREAK/ block the shading command will take effect immediatly.
  199.  
  200. To run the program you should just type in PRINTDOC and press enter. You will
  201. then be prompted to enter the name of up to 10 input files which will be
  202. used to create you manual. When you have finished entering filenames you should
  203. just press enter at which point you will be asked how many lines you want to
  204. print on each page. You are then given the opportunity to select a range of
  205. page numbers to print. Lastly you can decide where the output from the program
  206. should be sent. You can send output either directly to the printer or redirect
  207. it to a file.